HandStack 프로젝트 큰 그림 그리기

솔루션의 디렉토리와 모듈 경계를 읽고, 변경할 코드의 위치를 찾습니다.

QCN

잘 정리된 사무실 같은 HandStack

먼저 소스에서 바꿀 책임을 찾습니다. 디렉토리는 다음 역할로 나뉩니다.

  • 1.WebHost: 회사의 정문과 안내 데스크 역할
  • 2.Modules: 각 업무를 담당하는 전문 부서들
  • 3.Infrastructure: 모든 부서가 공유하는 핵심 인프라
  • 4.Tool: 업무 효율성을 높이는 각종 도구함
  • Solution Items: 전사 공통 규정 및 정책 문서
QCN

1.WebHost: 프로젝트의 시작점

  • 서버 실행의 진입점(Entry Point) 역할을 하는 웹 호스트 프로젝트가 있습니다.
  • 웹 애플리케이션의 환경 설정, 시작, 업무 모듈 서빙을 모두 이곳에서 담당합니다.
    • 비유하자면, 건물의 정문이자 모든 방문객을 맞는 안내 데스크와 같습니다.
  • ack 서버와 forbes 개발 템플릿이 있습니다.
QCN

2.Modules: 핵심 비즈니스 로직

  • 도메인 기반의 실제 업무 기능(모듈)들이 모여있는 곳입니다.
  • 각 모듈은 독립적으로 Application, Domain, Persistence, API 계층을 가질 수 있습니다.
  • 예시: 게시판 관리, 사용자 관리, 주문 처리 등
  • 비유하자면, 회계팀, 인사팀, 개발팀처럼 각자의 역할을 가진 ‘업무 부서’에 해당합니다.
  • 하나의 배포 단위 내에서 기능별로 모듈을 분리하는 모듈러 모놀리식 아키텍처의 핵심입니다.
QCN

3.Infrastructure: 공통 기반 시설

  • 서버 프로그램 기능을 위한 공통 인프라스트럭처 레이어입니다.
  • 데이터베이스 연결, 로깅, 인증 처리처럼 여러 모듈이 공유하는 시스템 자원이나 구현체를 제공합니다.
  • 비유하자면, 모든 부서가 함께 사용하는 ‘회의실’이나 ‘서버실’과 같은 공용 시설입니다.
  • HandStack 개발과 운영에 필요한 공통 API 집합입니다.

syn.js 라이브러리는 ack 프로젝트에 포함됩니다.
syn.uicontrols.js 라이브러리를 wwwroot 모듈에 포함됩니다.

QCN

4.Tool: 개발 보조 도구 (1/2)

  • 프로젝트 개발 및 배포, 유지보수를 위한 보조 도구와 유틸리티를 모아놓은 곳입니다.

  • CLI 도구, 데이터베이스 마이그레이션 스크립트 등이 포함될 수 있습니다.

  • 비유하자면, 업무 효율을 높여주는 ‘사무용품’ 또는 ‘공구함’과 같습니다.

QCN

4.Tool: 개발 보조 도구 (2/2)

  • 모든 기능은 자동화와 시스템 통합을 위해 CLI 를 우선하여 개발합니다.
    • Node.js, .NET Core, Python 기반의 CLI 는 API 함수로 만드는 비용이 적습니다.
QCN

Solution Items: 솔루션 공용 파일

  • Visual Studio 솔루션 레벨에서 사용하는 공용 파일들을 모아놓은 논리적 디렉토리입니다.
  • .gitignore나 Dockerfile, install, publish 스크립트 같이 솔루션 전체에 적용되는 파일들이 위치합니다.
  • 비유하자면, 모든 부서원이 반드시 참고해야 하는 ‘회사 공통 규정집’입니다.
QCN

직접 확인해보기

이제 Visual Studio에서 프로젝트를 직접 열어 구조를 살펴봅시다.

  1. Visual Studio 2022 Community를 실행합니다.
  2. $(HANDSTACK_SRC)/handstack.sln 파일을 엽니다.
  3. 솔루션 탐색기에서 오늘 배운 디렉토리들을 찾아보세요.
  4. 각 디렉토리의 역할과 설명을 마음속으로 매칭시켜 봅니다.
QCN

다시 보는 디렉토리 역할 정리하기

디렉토리 역할 (비유)
1.WebHost 프로젝트 시작점 (안내 데스크)
2.Modules 핵심 업무 기능 (업무 부서)
3.Infrastructure 공통 기반 시설 (공용 시설)
4.Tool 개발 보조 도구 (공구함)
Solution Items 솔루션 공용 파일 (회사 규정집)
QCN

업무의 핵심 모듈 라이브러리

  • HandStack의 백엔드는 모듈러 모놀리식 아키텍처를 기반으로 합니다.
  • 모듈은 개발 책임을 나누는 단위입니다. 독립 배포 여부는 의존성과 호스트 구성을 확인합니다.
  • 모듈들이 모여 하나의 큰 애플리케이션(ack 서버)을 구성합니다.
  • 이 모듈의 서버 측 구성 요소들을 살펴보겠습니다.
QCN

잠깐, 구분해 보기

모듈을 나누는 것과 서버를 여러 개로 나누는 것은 어떻게 다를까요?

QCN

아키텍처 간단 비교

HandStack은 모놀리식의 단순함과 마이크로서비스의 장점을 결합한 모듈러 모놀리식을 채택하여 개발 생산성과 유지보수성을 높였습니다.

HandStack 아키텍처에 대한 자세한 내용은 모듈러 모놀리식 아키텍처을 참고하세요.

아키텍처 장점 단점
모놀리식 개발 초기 단순함 유연성 부족, 배포 어려움
마이크로서비스 높은 유연성, 확장성 복잡성 증가, 관리 비용
모듈러 모놀리식 균형 잡힌 접근 초기 설계 중요성 증가
QCN

여러 개의 독립된 모듈로 구분된 애플리케이션 (1/2)

  • 모듈러 모놀리식은 애플리케이션의 도메인을 더 작고 관리하기 쉬운 컴포넌트 또는 모듈로 나누는 아키텍처 접근법 입니다.

  • 코드베이스를 논리적이고 구조적인 디렉토리로 구성해서, 시스템 기능 간의 관심사를 분리하고 경계를 명확하게 합니다.

QCN

여러 개의 독립된 모듈로 구분된 애플리케이션 (2/2)

QCN

애플리케이션 아키텍처 예시 (1/2)

  • 단일 호스트

    • ack + (wwwroot/transact/dbclient/graphclient/function/command/prompter/repository/logger/checkup/forwarder)

  • 2 개 호스트

    • ack + (wwwroot/transact/checkup)
    • ack + (dbclient/graphclient/function/command/prompter/repository/logger/forwarder)
QCN

애플리케이션 아키텍처 예시 (2/2)

  • 3 개 호스트
    • ack + (wwwroot/transact)
    • ack + (dbclient/graphclient/function/command/prompter)
    • ack + (repository/logger/checkup/forwarder)

한 머신에서도 포트를 나눠 여러 호스트를 실행할 수 있습니다. 프로세스 분리만으로 데이터·배포·장애 경계가 자동 분리되지는 않습니다.

QCN

모듈 프로젝트의 SDK 개념

.NET Core 프로젝트의 모듈 프로젝트 SDK는 컴포넌트 기반 UI, Razor Pages, Blazor 컴포넌트를 ASP.NET Core의 모든 기능을 사용 가능한 라이브러리 형태로 개발합니다.

SDK ID 사용 용도 예시
Microsoft.NET.Sdk 콘솔 앱, 윈폼, 라이브러리 dotnet new console, dotnet new classlib
Microsoft.NET.Sdk.Web ASP.NET Core 웹 앱, API dotnet new mvc, dotnet new webapi
Microsoft.NET.Sdk.Razor Razor 컴포넌트 라이브러리 dotnet new razorclasslib
Microsoft.NET.Sdk.BlazorWebAssembly Blazor WASM SPA 앱 dotnet new blazorwasm
Microsoft.NET.Sdk.Worker Worker 서비스 dotnet new worker
Aspire.AppHost.Sdk Aspire 클라우드 네이티브 앱 dotnet new aspire-app
MSTest.Sdk MSTest 기반 테스트 dotnet new mstest
QCN

애플리케이션을 위해 필요한 주요 기능 (1/2)

비즈니스 요구사항에 맞게 기능을 개발 하기 위해 다음의 기능들을 하나 또는 각각의 module 단위로 개발 할 수 있습니다.

  • Database CRUD 거래

  • Graph 데이터 조회와 관계 분석

  • 외부 시스템과 연동을 위한 기능 개발

  • CLI, Web URL, LLM 프롬프트 호출

  • 클라이언트 인증 및 권한

QCN

애플리케이션을 위해 필요한 주요 기능 (2/2)

  • 파일 업로드/다운로드 기능

  • 화면 개발에 필요한 UI 컴포넌트

이외에도 모니터링, 장애 확인등등 안정적인 운영을 위해 다양한 부가 기능들을 고려해야 합니다.

QCN

공식 modules (1/3)

HandStack은 이러한 애플리케이션을 개발하기 위한 부분을 논리적으로 추상화하여 module로 개발 및 제공합니다.

QCN

공식 modules (2/3)

module명 설명
checkup 테넌트 앱 개발 및 운영 기능 관리
command 계약 기반 CLI 프로세스와 Web URL 호출 실행
dbclient SQL Server, Oracle, MySQL & MariaDB, PostgreSQL, SQLite SQL을 관리
forwarder requestKey 기반 화이트리스트 포워드 프록시 제공
function C# 또는 Node.js 기반 Function 개발 기능 관리
graphclient Neo4j, Memgraph 기반 Cypher 실행 관리
logger module 요청/응답 구간 주요 이벤트 로그 수집 관리
QCN

공식 modules (3/3)

module명 설명
prompter LLM 프롬프트 계약 실행 및 도구 호출 관리
repository 단일, 다중, 이미지, 첨부파일 등등 파일 업로드/다운로드 관리
transact 거래 요청 검증 및 접근 제어 관리와 요청 정보를 dbclient, function 등등 module로 라우팅 기능 관리
wwwroot 웹 공통 static assets 및 화면 단위 소스 호스팅 관리
QCN

규모에 따른 어플리케이션 모듈 구성 (1/2)

느슨하게 결합된 모듈을 만들 수 있고, 인터페이스를 일관되게 유지 할 수 있으며, 향후 마이크로서비스 아키텍처로 전환 할 경우에도 유리하게 작용될 수 있습니다.

QCN

규모에 따른 어플리케이션 모듈 구성 (2/2)

QCN

개발/운영 비용 간 균형 잡기

개발 자동화의 효과와 운영 비용을 별도로 측정합니다.

  • 개발 단계: .NET Core의 크로스플랫폼, CLI, SDK 프로젝트, 최신 언어 기능, AI 지원 → 저비용, 고속 개발 가능
  • 운영 단계: 사용자가 늘어날수록 인프라, 모니터링, 백업, 스케일링, 보안, 법적 대응 등 운영비용 지속 증가

고객의 요구에 맞춰 셀프 호스트, 클라우드, 하이브리드 방식의 개발과 운영을 해야합니다.

QCN

구조를 읽는 기준

  • 호스트·업무 모듈·공통 기반·도구·솔루션 공용 파일을 구분합니다.
  • 모듈 종속성과 배포 단위를 확인합니다.
  • 확장성만 보지 않고 운영 복잡성과 비용을 함께 비교합니다.
QCN

발표: 첫 화면의 목표를 말한 뒤 핵심 개념과 예제로 진행합니다. 확인 질문 뒤에는 답할 시간을 주고, 마지막 완료 기준을 남겨 질문을 받습니다. 발표 구성 참고: MIT OpenCourseWare, Patrick Winston, How to Speak (2018), https://ocw.mit.edu/courses/res-tll-005-how-to-speak-january-iap-2018/pages/how-to-speak/

질문 후 잠시 기다립니다. 답이 없으면 앞에서 본 예제를 다시 가리킵니다. 확인할 답: 코드 경계와 배포 경계는 별개입니다. 분리 호스트에는 통신·운영 비용도 생깁니다. 다음 주제로 넘어가기 전에 차이를 청중의 표현으로 한 번 확인합니다.

질문을 받는 동안 이 확인 기준을 화면에 남깁니다. 청중이 자신의 업무에 적용할 다음 행동 하나를 고르게 합니다.